chore(brand): remove web3 jargon and em-dashes across docs#132
Merged
Conversation
Per ICP brand guidelines: - Replace all em-dashes (—) with colons, periods, or parentheses across all editable docs (78 files, ~1400 substitutions) - Remove "seamlessly" from glossary boundary-nodes definition - Change "Web-native smart contracts" card title → "Onchain web apps" - Replace "smart contract" when used as the primary descriptor for ICP canisters (canisters.md, network-overview.md, chain-key-tokens.mdx); keep in cross-chain comparisons where technically accurate - Replace "dapp/dApp/dapps" → "app/apps" in all prose; preserve Candid field names (RegisterDappCanisters, DeregisterDappCanisters, dapps:) and the NNS product name - Change "Decentralized oracle" → "Trustless oracle" in chain-fusion.md - Remove "fully decentralized application" pitch from choose-your-path.md - Fix N/A em-dash table cells → hyphens (chain-fusion, ethereum, protocol) - Fix "a dapp" → "an app" article agreement throughout Excluded from changes (synced or spec files): - docs/languages/motoko/ (auto-synced) - docs/guides/tools/migrating-from-dfx.md (synced from icp-cli) - docs/reference/ic-interface-spec.md (protocol spec) - docs/reference/internet-identity-spec.md (protocol spec) - docs/reference/candid-spec.md (protocol spec) - docs/reference/glossary.md "smart contract" and "dapp" entries (definitions)
Pre-existing violations surfaced because both files were touched in the em-dash pass. Reword explanation prose to avoid the banned string while preserving the meaning.
marc0olo
commented
Apr 23, 2026
| Canisters are the compute units of the Internet Computer. Each canister bundles compiled WebAssembly code with its own persistent state into a single unit that the network executes, replicates, and secures. You deploy code to a canister, send it messages, and the network guarantees that every honest node in the subnet reaches the same result. | ||
|
|
||
| Unlike smart contracts on most blockchains, canisters can serve web pages over HTTP, store gigabytes of data, make calls to external APIs, sign transactions on other chains, and run scheduled tasks autonomously — all without external infrastructure. | ||
| Unlike smart contracts on most blockchains, canisters can serve web pages over HTTP, store gigabytes of data, make calls to external APIs, sign transactions on other chains, and run scheduled tasks autonomously, all without external infrastructure. |
Member
Author
There was a problem hiding this comment.
can we replace "unlike smart contracts on most blockchains" somehow? I think at least the term "smart contract" can be removed. maybe it can be rephrased entirely without losing the meaning.
marc0olo
commented
Apr 23, 2026
| ```bash | ||
| icp canister call sns_root list_sns_canisters '(record {})' -e ic | ||
| # Expected: your dapp canisters listed under "dapps" | ||
| # Expected: your app canisters listed under "apps" |
Member
Author
There was a problem hiding this comment.
the field in the response is actually dapps as defined in the candid interface. we should not make wrong claims.
please check other places for potential wrong renames, too.
marc0olo
commented
Apr 23, 2026
| - Portal: building-apps/network-features/vetkeys/ (9 files: intro, API, BLS-signatures, DKMS, encrypted-storage, IBE, timelock, VRF, demos) | ||
| - icskills: vetkd | ||
| - Examples: vetkd (both), vetkeys (both), encrypted-notes-dapp-vetkd (both), filevault (Motoko) | ||
| - Examples: vetkd (both), vetkeys (both), encrypted-notes-app-vetkd (both), filevault (Motoko) |
Member
Author
There was a problem hiding this comment.
we cannot change the name of an example here. this is currently just a stub anyway that we need to populate soon.
marc0olo
commented
Apr 23, 2026
Member
Author
marc0olo
left a comment
marc0olo
left a comment
There was a problem hiding this comment.
please address the comments
- canisters.md: rephrase 'Unlike smart contracts on most blockchains' to 'Unlike programs on most other blockchains' - encryption.md: revert encrypted-notes-dapp-vetkd (real example repo name, must not change) - testing.md: revert dapp canisters / dapps field name (actual Candid field in SNS response)
Member
Author
|
Feedback addressed:
|
Member
Author
|
Feedback addressed:
|
marc0olo
added a commit
that referenced
this pull request
Apr 24, 2026
## Summary - Replaces all prose and link-list ` -- ` patterns with `:` across 10 docs pages - Follows ICP brand guidelines (no em-dashes or em-dash substitutes) - Consistent with the prior cleanup in PR #132 ## Files changed - `docs/guides/index.md`, `docs/concepts/index.md`, `docs/reference/index.md`, `docs/languages/index.md` — index page link lists - `docs/getting-started/choose-your-path.md` — link lists and one prose sentence - `docs/getting-started/project-structure.mdx` — "Next steps" link list - `docs/concepts/orthogonal-persistence.md` — prose and link lists - `docs/guides/canister-calls/onchain-calls.mdx` — prose and "Next steps" link list - `docs/guides/canister-management/settings.mdx` — definition terms and link list - `docs/guides/frontends/asset-canister.md` — field definitions and link list ## Left unchanged (legitimate uses) - Shell end-of-options `--` in code blocks (`bazel run`, `sh -s`) - Pseudocode comment notation in `certified-variables.md` and `certification.md` - Table N/A cells in `token-standards.md` - Stub placeholder pages (`vetkeys.md`, `encryption.md`) - Auto-synced Motoko changelog ## Sync recommendation hand-written
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
canisters.mddescription and opening sentence no longer call canisters "smart contracts" (kept the comparison section, which is educationally accurate)chain-key-tokens.mdx: "ICP smart contracts" → "ICP canisters" (2 instances)network-overview.md: "run smart contracts (canisters)" → "run canisters"quickstart.md: removed "smart contracts that run on the Internet Computer" parentheticalchain-fusion.md: "Decentralized oracle" → "Trustless oracle"choose-your-path.md: "fully decentralized application" → "tamperproof application"glossary.md: removed "seamlessly" from boundary-nodes definitionRegisterDappCanisters,DeregisterDappCanisters), API identifiers, and the glossary term definition itself.Preserved without changes (technically accurate or synced):
smart contractin all cross-chain comparison contexts (Ethereum contracts, EVM contracts, etc.)smart contractin the glossary definition andcanisters.mdcomparison sectiondecentralize/decentralizationin SNS context (it's what the SNS literally does)blockchainwhen referring to other chains (Bitcoin, Ethereum, etc.)DeFiin DeFi-specific guidesworkloadas a technical CS term in optimization/perf guidesdocs/languages/motoko/,migrating-from-dfx.mdic-interface-spec.md,internet-identity-spec.md,candid-spec.mdSync recommendation
hand-written